Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/STUTTGART/LANG/ADA/GNAT/!gcc/gnat/Help

Text File | 1996-11-23 | 24KB | 597 lines

                          GNAT
                        ~~~~~~~~

This is a port of the GNAT (GNU/NYU Ada Translator) compiler (version
3.0.3) for the Ada programming language to the Acorn range of ARM based
machines, running under RISC OS. As such, this package is covered by the
FSF General Public License (see the files gnat.Copying and
gnat.CopyingLib, and later for details).

This port is © 1995, 1996 Peter Burwood

As with as GNU programs, THERE IS NO WARRANTY OF ANY SORT

IMPORTANT: GNAT REQUIRES A LOT OF MEMORY. The wimpslot needs to be at
least 6000K in size. GNAT is NOT capable of grabbing extra memory, so
the initial WimpSlot sets the maximum memory available. GNAT can use
dynamic areas on the Risc PC for the heap and stack and in this mode the
wimpslot needs to be at least 3000K in size (though running from AMU can
increase this). See Dynamic Areas below for further details.

Thanks go to various people for the help and assistance that they have
given me. These are :

The GNAT development team for writing GNAT.

Nick Burrett, Simon Callan, Richard Earnshaw, Michael Ben-Gershon and
Pietr Schonmaker, for most of the hard work involved in the ARM backend.

Niklas RÖjemo, for the assembler `as'

Huw Rogers and Simon Callan, for Unixlib.


Files
=====

There are over 900 files in the GNAT binary distribution, so I won't
list them all, but the overall contents of this archive is as follows :-

   !gcc.adainc...        - Ada 95 standard library and GNAT extensions.
   !gcc.bin...           - GNAT binaries (see gnatinfo) and gcc binary.
   !gcc.gcc.adalib...    - object files for Ada library.
   !gcc.gcc.o.libgnat    - support library for GNAT using UnixLib.
   !gcc.gcc.o.libgnat_cc - support library for GNAT using SharedCLibrary.
   !gcc.gcc.o.libm       - empty maths library to stop complaints since
                           the functions are in UnixLib and stubs anyway.
   !gcc.gnat             - documentation for GNAT.
   !gcc.gnat.examples    - examples from standard GNAT distribution
                           included is a utility that works like Unix's
                           rm command which is used by the makefile.


Installation
============

Before attempting to use GNAT, it should be noted that this distribution
of GNAT is not standalone, consisting of only the GNAT compiler, tools
and library.

GNAT 3.03 requires GCC 2.7.2, as supplied by Nick Burrett and available
from Acorn ftp sites such as Hensa, to be installed. Unpack this
complete archive into the GCC 2.7.2 directory. Double click on !GCC to
ensure the environment is correctly set for the compiler.

There is an alternative binary for !gcc.bin.gcc called !gcc.bin.gcc-gnat
which may need to be copied over the original !gcc.bin.gcc file from the
GCC 2.7.2 distribution (after taking a backup of the original file).
This is only necessary if the version from GCC 2.7.2 fails to work
properly, by which I mean that running the makefile in the examples
directory fails. The version in this archive understands Ada, C, C++,
Fortran and Pascal filenames, so should work with those GNU compilers.

GNAT 3.03 also requires UnixLib 3.7b or later, but not UnixLib 4.0. GNAT
will not work with UnixLib 3.6e, but it might work with UnixLib 3.7a.
The following commands should be part of the !Run file that comes with
GCC 2.7.2, but if not, then please add them before trying to use GNAT.

  | Set search paths for the Ada run time library files
  *Set GNATada$Path <Obey$Dir>.adainc.
  *Set GNATInc$Path gnatada:1.,gnatada:2.,gnatada:3.,gnatada:4.,gnatada:5.,gnatada:6.,gnatada:7.
  *Set GNATlib$Path gcc:adalib.1.,gcc:adalib.2.,gcc:adalib.3.,gcc:adalib.4.,gcc:adalib.5.,gcc:adalib.6.,gcc:adalib.7.

  | Set search path for gnatbl
  *SetMacro path <Run$Path>

  | Enable dynamic area usage for GnatMake
  *Set GnatMake_Heap ""


GNAT uses the following filename extensions :-

   .ads   - Ada specifications (similar to C .h files).
   .adb   - Ada bodies (similar to C .c files).
   .adc   - The file gnat.adc can be used to override the normal file
            naming convention (see !gcc.gnat.gnatinfo).
   .ali   - GNAT's source code library support files (these are
            generated by the compiler).
   .xrs   - cross reference file for corresponding .ads file
   .xrb   - cross reference file for corresponding .adb file

and these extensions must be included in the UnixFS$sfix environment
variable. GCC 2.7.2's !Run file should already include these, but if not
then change the '*Set UnixFS$sfix ...' to something like this :-

  *Set UnixFS$sfix "a:c:f:h:i:l:o:p:s:y:ads:adb:ali:adc:xrb:xrs"

Be careful when adjusting this variable if you are also using other GNU
compilers. The additional file extensions required for GNAT are

   ":ads:adb:ali:adc:xrb:xrs"


Using GNAT
==========

See the gnatinfo file in the gnat directory and the GCC-FAQ which is in
the GCC 2.7.2 archive. Also look at the makefile in the gnat.examples
directory which can be executed with amu. Ensure that you have a large
enough WimpSlot, otherwise AMU will exit with a fatal error.

All of the command line switches mentioned in the GCC documentation also
work with GNAT, so for example, throwback is enabled with -mthrowback.


Using the SharedCLibrary
========================

It is actually possible to use GNAT without UnixLib by using the
SharedCLibrary and linking against Acorn's stubs. Do not try to use
UnixLib and Acorn's stubs together in the same program - it will not
work.

To use Acorn's stubs you will need Acorn's C compiler or a copy of
gstubs from ftp sites such as Hensa. You must link with the libgnat_cc
library instead of the libgnat library (these files are in !GCC.gcc.o).
This can be accomplished by either replacing libgnat with libgnat_cc
(after you have made a safe copy of libgnat) or by using
"-mstubs -lgnat_cc" with gnatbl. The makefile in the examples directory
has a line commented out which illustrates this method of using the
SharedCLibrary. Simply uncomment this line and build the example
programs with the makefile.


Using other C libraries such as UnixLib, DeskLib, OSLib and the Toolbox
=======================================================================

Until Ada bindings become available for these libraries, there are
basically two approaches. Write simple veneers for the function or SWI,
or write the easy bits in C and provide a narrow interface to call from
Ada. Try and avoid C functions which take a variable number of arguments
and extensible arrays. Functions taking a variable number of arguments
can be called by overloading the interface functions with differing
number of arguments. There is an alternative, but it is very messy and I
won't go into it here. A messy solution also exists for extensible
arrays, but again I'll avoid the issue for now. Anonymous unions also
cause problems and are not representable with GNAT 3.03 (a later version
of GNAT provides a pragma to overcome this) and so must be avoided.

An example of a general SWI veneer and a call to OS_Bell is provided in
the !gcc.gnat.examples.swi directory. The kernel package is just a thin
binding to an assembler generic swi routine as exists in UnixLib and the
SharedCLibrary. In a larger system, this package would be better as a
child package of a package called RiscOS.


File Name Rules
===============

The gnatinfo file explains how GNAT expects to find files. This naming
convention is necessary for GNAT to find `with'ed units. Under RISC OS,
the file name is crunched to 10 characters rather than 8 characters as
with DOS. gnatk8 can be used to find out what the krunched name of a
file should be by using `10' as the second argument to gnatk8.

File name rules can be overridden with the pragma Source_File_Name as
described in gnatinfo.

If you need to use GnatChop to convert some Ada files to the GNAT naming
convention, then you may be unlucky and hit a shortcoming of GnatChop.
When the krunched name for two or more units is not unique, then
GnatChop will fail to chop the original file but will report the
duplicate krunched name that it is trying to reuse. This problem can be
circumvented by hand chopping the units which krunch to the same file
name and save them as unique file names and use pragma Source_File_Name
so that the compiler can find them.


Dynamic Areas
=============

I have modified UnixLib to use dynamic areas on the Risc PC and these
modifications have been included in UnixLib 3.7a. This section applies
to all GNU compilers supplied by either Nick Burrett, myself or
(hopefully) anyone else providing they have used UnixLib 3.7a. A
description of using dynamic areas is included with UnixLib 3.7a.
Basically, use

  *Set GCC_Heap ""

to enable dynamic areas for the compiler and

  *UnSet GCC_Heap

to disable dynamic areas for the compiler.

Before running a program set the wimpslot in the normal way, but it only
needs to be large enough to hold the sum of the largest executables that
can be run concurrently. e.g., with gcc, use the unsqueezed size of gcc
plus cc1. When running from a command line amu remember to allow
additional space for the amu executable and amu's workspace (though this
is tricky to estimate!).

If other programs that form part of GNAT are run directly from the
command line, e.g., gnatmake, then separate environment variables must
be set to allow these programs to use dynamic areas for the program's
heap. So, with gnatmake,

   *Set gnatmake_heap ""

This applies to gnatmake, gnatbl, gnatchop and gnatf. You should not
invoke any of the other executables directly, apart from gnatk8 and
gnatk8 does not use enough memory to warrant using a dynamic area.

If you enable dynamic areas and you still run out of memory when
compiling, then I suggest that you get something like Clares' Virtualise
product which will provide virtual memory for dynamic areas. Note, I
have no connection with this program, but I have used it when compiling
Ada programs which needed more memory than I have. Alternatively,
consider buying more memory.


Speeding up compilation
=======================

If you have plenty of ram, then moving the Ada library units onto a ram
disc should speed up compilations which "with" a lot of standard library
units. This will require a ram disc of nearly 3MB, so is best done only
if you have more than 20MB of ram. If the standard libraries are placed
on the ram disc, then the GNATada$Path should be redefined to point to
the ram disc. The Ada library units are the !gcc.adainc directory.

Placing the main compiler, gnat1, on the ram disc will also help,
providing you have enough free ram. If gnat1 is put on the ram disc,
then ensure that the ram location appears earlier in the run path.


Overcoming the limit of 77 files in a directory
===============================================

Ada projects with more than 77 files are awkward to manage under RISC OS
due to the RISC OS directory restriction. One solution is to try using a
dos image disc, but be aware that this means all your files are really
in a single file and if this image file is corrupted in some way you
risk losing all your files.

Alternatively (and probably better) is to split your source into
sub-systems and build these each in their own directory. This is
especially important when GnatMake is used since the output of GnatMake
is always to the current directory even when it is compiling a file from
another directory. When a sub-system needs to use another sub-system,
then build the independent one first and add its directory to the search
path.

Before I go any further, please read the section "Search paths and the
Run Time Library" in gnatinfo. The last search rule (unix only) also
applies to RISC OS.

The default location is GNATinc: for the RTL source and GNATlib: for the
RTL objects. Note that the environment variables `ADA_INCLUDE_PATH' and
`ADA_OBJECTS_PATH' are used unchanged, that is, do not try using
something like AdaInclude$Path because it will not work. Obviously, the
case of the environment variable is unimportant under RISC OS. Also, do
not alter the GNATinc$Path and GNATlib$Path variables set in !gcc.!Run
since GNAT is unlikely to work if you do. An alternative to using
`ADA_INCLUDE_PATH' and `ADA_OBJECTS_PATH' is to use -I to specify the
include directories - just as you would with C.

Now, consider the following example where we have a library directory
providing a sub-system and your main project directory which pulls all
the sub-systems together.

I created the following

           RAM::0.$
              |
        --------------
        |            |
       lib         home
        |            |
     info.ads      test_info.adb

Then issued the following commands

---------------------
*dir ram::0.$.home
*wimpslot -min 4000k
|enable dynamic areas for gnatmake and anything it invokes
*Set gnatmake_heap ""
*gnatmake -v -Iram::0.$.lib test_info.adb

GNAT Make Version 3.03 Copyright 1995 Free Software Foundation, Inc.
Checking --> test_info.adb
  "test_info.ali" missing.  **Recompile**
gcc -c -Iram::0.$.lib test_info.adb
Checking --> ram::0.$.lib/info.ads
  "info.ali" missing.  **Recompile**
gcc -c -Iram::0.$.lib ram::0.$.lib/info.ads
gnatbind -Iram::0.$.lib test_info.ali
gnatbl test_info.ali -linkonly
---------------------

Now this managed to create an executable, but it has put info.{ali.o} in
the ram::0.$.home directory. This is not something we want since the
home directory is soon going to hit the damn 77 file limit. Also, it's
wrong from the point of view of not having info's compiled files in the
same directory as the source for info.

So, after cleaning up the files so we just have the source files, I then
issued the following commands

---------------------
*dir ram::0.$.lib
*gnatmake -v -c info.ads

GNAT Make Version 3.03 Copyright 1995 Free Software Foundation, Inc.
Checking --> info.ads
  "info.ali" missing.  **Recompile**
gcc -c info.ads
*dir ^.home
*gnatmake -Iram::0.$.lib -v test_info.adb

GNAT Make Version 3.03 Copyright 1995 Free Software Foundation, Inc.
Checking --> test_info.adb
  "test_info.ali" missing.  **Recompile**
gcc -c -Iram::0.$.lib test_info.adb
Checking --> ram::0.$.lib/info.ads
gnatbind -Iram::0.$.lib test_info.ali
gnatbl test_info.ali -linkonly
---------------------

Now, this is what we need, an executable and the files all in the
correct places, i.e.,

           RAM::0.$
              |
        --------------
        |            |
       lib         home
        |            |
     info.ads      test_info.adb
     info.ali      test_info.ali
     info.o        test_info.o
                   test_info

We can also try this with the Ada_Include_Path and Ada_Objects_Path. So
with info.{ali,o} already in the lib directory and only test_info.adb in
the home directory, I issued the following commands.

---------------------
*set Ada_Include_Path ram::0.$.lib
*set Ada_Objects_Path ram::0.$.lib
*gnatmake -v  test_info.adb

GNAT Make Version 3.03 Copyright 1995 Free Software Foundation, Inc.
Checking --> test_info.adb
  "test_info.ali" missing.  **Recompile**
gcc -c test_info.adb
Checking --> ram::0.$.lib/info.ads
gnatbind test_info.ali
gnatbl test_info.ali -linkonly
---------------------

Please notice that with Ada_Include_Path and Ada_Objects_Path you do not
have a trailing "." on the directory names. This is because each comma
separated part of these environment variables is checked for the
location of the file (info.ads in this case) by gnat itself. The GNATInc
and GNATLib bits work differently (they have a trailing ".") because
gnat only uses gnatinc: and gnatlib: and gets RISC OS to do the search.

Right, now onto a more complicated case involving several subsystems.
When there are several subsystems, I would recommend that
Ada_Include_Path and Ada_Objects_Path are not used because it is easy to
soon lose track of the dependancies between the subsystems and end up
with objects in the wrong directory. It is much better to use multiple
-I switches.

Build a directory tree structure something like this.

                  ...project
                      |
          -------------------------------------------
          |         |          |          |         |
       common    subsys1    subsys2    subsys3    main
                                          |
                                       -------
                                       |     |
                                       1     2

 common  - global files used by too many files.
 subsys1 - a subsystem with less than 77 files.
 subsys2 - another subsystem.
 subsys3 - a larger subsystem that needs 2 directories to overcome 77
           file limit.
 main    - the project specific bits including the main unit.

There is one thing about the 77 file limit you may or may not come across.
While you can have say 77 .ads and 77 .adb files in a single directory,
you may not be able to compile all the files in the directory. This
happens when there are some .ads that have no corresponding .adb. I
typically put a maximum of 60 files into a single directory, since this
allows for specs without bodies. If a lot of your .adb files are
separates then you are less likely to hit this limitation since
separates don't generate .ali and .o files.

The problematic subsystem is subsys3. This will probably be tricky to
make with a single gnatmake because a single gnatmake would put some of
the objects in the wrong subdirectory of subsys3 (e.g., in 1 instead of
2), so you may have to use several invocations of gnatmake. Effectively,
treat each subdirectory of subsys3 as a separate subsystem. When issuing
the gnatmake command, ensure that you are in the correct directory.

Another problem is common. This directory is unlikely to have a single
unit which has a transitive closure encompassing all the other units in
the directory. You would probably be best using "gcc -c" or "gnatmake
-c" on all the files in this directory (gnatmake has the advantage of
checking whether compilation is necessary).

Perhaps something along these lines.

*dir project
*dir common
*gnatmake -c file1.adb
*gnatmake -c file7.adb
*dir ^.subsys1
*gnatmake -I../common -c subsys1.adb
*dir ^.subsys2
*gnatmake -I../common -c subsys2.adb
*dir ^.subsys3.1
*gnatmake -I../../common -c subsys311.adb
*gnatmake -I../../common -c subsys315.adb
*dir ^.2
*gnatmake -I../../common -I../1 -c subsys32.adb
*dir ^.^.main
*gnatmake -I../common -I../subsys1 -I../subsys2 -I../subsys3/1 -I../subsys3/2 main.adb

Not wonderful I know, but there is really no alternative while the 77
file limit exists.

Note, I have used Unix style directory names with the -I switches, but
RISC OS directory specifications could be used. You may also find it
easier if path variables are declared to locate the directories. So, in
the above example, we would define something like this

*Set common$path adfs::4.$.project.common.
*Set subsys1$path adfs::4.$.project.subsys1.
*Set subsys2$path adfs::4.$.project.subsys2.
*Set subsys3$path adfs::4.$.project.subsys3.

and the above commands would become

*dir project
*dir common
*gnatmake -c file1.adb
*gnatmake -c file7.adb
*dir ^.subsys1
*gnatmake -Icommon:/ -c subsys1.adb
*dir ^.subsys2
*gnatmake -Icommon:/ -c subsys2.adb
*dir ^.subsys3.1
*gnatmake -Icommon:/ -c subsys311.adb
*gnatmake -Icommon:/ -c subsys315.adb
*dir ^.2
*gnatmake -Icommon:/ -Isubsys3:1/ -c subsys32.adb
*dir ^.^.main
*gnatmake -Icommon:/ -Isubsys1:/ -Isubsys2:/ -Isubsys3:1/ -Isubsys3:2/ main.adb

This is all necessary because as the gnatinfo file says,

  "The compiler outputs its object files and ALI files in the current working
directory (NOTE: the object file can be redirected with the -o option;
however, gcc and gnat1 have not been coordinated on this so the ALI file
will not go to the right place -- DON'T DO THIS)."

So, for now you have to do something yucky along the lines above. I
should contact the gnat team to see whether they are going to address
the limitation of the -o switch and .ali files so that gnatmake can
incoporate it. Alternatively, I could modify gnatmake to change the
current working directory before issuing the compilations. However, I
suspect this change would upset a lot of other peoples makefiles (across
all platforms) so the change may not be accepted back into the main gnat
source.

The other thing to do is to use make files and use a make system such
as Acorn's make utility, amu. I use this for rebuilding gnat and it does
work, but you have to employ a couple of tricks with .suffixes as used
in the makefile in the examples directory.


Known problems
==============

Known, damn if I'd known about them, I'd have fixed them. Please tell me
all that you find and see below for how to contact me and the file
!gcc.gnat.Bugs for what to do if you have found a bug.

Actually AMU behaviour is fun, see the examples directory for a working
makefile.

RISC OS specific documentation is also lacking (i.e., no Intro file). It
will improve soon providing you send explanations of problems.

GCC 2.4.5 produces incompatible code with 2.7.2 and that is simply that.

GnatChop does not cope well with separates because it adds a command to
the generated script for separates when it shouldn't. This is a bug in
the main GNAT source and thus is not specific to RISC OS. The '-w'
switch does not work very well either, so be careful about overwriting
files. When using GnatChop, rename the source file to files/src (RISC OS
name) and use "gnatchop -s files.src" to chop the files. Again, the 77
file limit is a problem, so either use a dos image file or split
files/src into smaller units before chopping, then split into
subsystems.


Known Restrictions
==================

No tasking for RISC OS version, yet!

No interfaces specifications for the Wimp, though I am working on
providing libraries. For the time being, implement a tight interface to
the wimp with some high level C functions and write your own interface
file.


Pointers to Ada related items on the Web
========================================

The main GNAT ftp site is ftp://ftp.cs.nyu.edu:/pub/gnat.

Here are some WWW URL's for Ada. You can get to many other sites that
have Ada related information from the first two pointers.

  Ada meta sites
    http://www.cera2.com/ada.htm
  Ada IC
    http://sw-eng.falls-chruch.va.us/AdaIC/
  Home of the Brave Ada programmers
    http://www.adahome.com/
  Ada Lovelace tutorials
    http://www.adahome.com/Tutorials/Lovelace/lovelace.html
  AdaBasis - reusable component repository
    http://www.informatik.uni-stuttgart.de/ifi/ps/ada-software/ada-software.html
  Ada SIG
    http://www.acm.org/sigada/
  Ada UK
    http://www.adauk.org.uk/
  GNAT Home
    http://www.gnat.com/
  Reusable Component Library
    http://lglwww.epfl.ch/Components

See the end of the file !gcc.gnat.gnatinfo for some other pointers.


History
=======

   May-1996
     First RISC OS release of GNAT 3.01

   Oct-1996
     gnatbind now copes with rooted directories at link phase.
     gcc backend bug fixed which had caused a bug in Text_IO stopping
     it from opening files (raising NAME_ERROR) and in the numerics
     elemenatary functions for long and long long floats.

   Nov-1996
     Second RISC OS release of GNAT 3.01

   Nov-1996
     First RISC OS release of GNAT 3.03

Contacting me
=============

If you wish to contact me, then I can be contacted as follows:

Peter Burwood
205 Masons Avenue
Harrow
Middlesex
HA3 5AZ

Email: [e-mail] for gnat related queries
       [e-mail] for anything else